Table of Contents

Overview

This section provides a reference guide for the tools that power the Connect IQ system.

Monkey C Language Reference

Monkey C is an object-oriented language built from the ground up, designed for easy app development on wearable devices. If you’ve worked with dynamic languages in the past like Java™, PHP, Ruby, or Python™, Monkey C should be very familiar.

The goal of Monkey C is to round the sharp edges of app development, allowing developers to focus more on the customer and less on resource constraints. Monkey C compiles into byte code that is interpreted by a virtual machine, similar to Java. Also like Java, objects are allocated on the heap, and the virtual machine cleans up memory.

Language Essentials

Data Types

Monkey C is a duck typed language[1], and does not have true primitive types. The Boolean, Char, Number, Long, Float, and Double types are all objects, which means primitives can have methods just like other objects. In languages like Java or C++, types must be declared for each function parameter and return value. The Monkey C compiler does not verify type safety, however, and instead runtime errors occur when functions mishandle objects. This provides great flexibility to developers, but in exchange the compiler cannot perform static type checking like in C++ or Java. Using operators like instanceof and has can help avoid potential typing issues.

The basic data types supported by Monkey C are:

Monkey C also supports two container types:

*Requires heap allocation, which requires more memory than a 32-bit type.

Keywords

There are several keywords, operators, and reserved words in the Monkey C programming language that cannot be used as variables or symbols in your programs:

Operators

Monkey C supports several useful operators outlined below. In the examples below, assume a = 10, b = 5, x = 1, y = 0, m = true, and n = false.

Arithmetic Operators

Relational Operators

Logical Operators

In Monkey C the following apply: * If an object is not null, it is evaluated as true. A value of 0 is evaluated as false. * A ! applied to a Number or Long is the same as applying a ~.

When comparing non-Boolean values in logical expressions: * The expression x && y first evaluates x. If x is false, its value is returned; otherwise, y is evaluated and the resulting value is returned. * The expression x || y first evaluates x. If x is true, its value is returned; otherwise, y is evaluated and the resulting value is returned.

Bitwise Operators

Bitwise operators perform operations on binary values, bit-by-bit. These adhere to conventions illustrated by the following truth table:

Assume p = 3 and q = 1. If written as byte values in binary, p is 0000 0011 and q is 0000 0001.

Assignment Operators

Miscellaneous Operators

Operator Precedence

Operator precedence determines which parts of an expression will be evaluated first. The list below groups the operators by precedence, the highest appearing at the top of the table, and the lowest at the bottom.

Variables and Expressions

Comments

Commented statements are ignored by the compiler. Monkey C supports multi-line (/* */) and single-line (//) comments. Here is an example of a multi-line comment:

/*
This is a multi-line comment. Notice that the information
continues to appear as a comment as long as it remains
inside the comment delimiters.
*/

Single-line comments may appear on their own line, or may appear in-line with other Monkey C code:

using Toybox.System;

// This is a single-line comment on its own line
System.println("Hello World!");  // This comment shares a line with code that will execute

Declaring Variables

All variables must be declared before use with the var keyword. Since Monkey C is a duck typed language[1], it is not necessary to delcare each variable’s type.

var x = 5;            // A 32-bit integer value
var myString = "";    // An empty string
var n = null;         // Null value
var f = 4.0d;         // A 64-bit floating point value

The flexibility of duck typing means there are things watch out for:

var arr = new[10];     // Create a new array; since the values are unassigned, they are initialized as 'null'
var z = arr[0] + 5;    // Attempt to add a Number to a null array element. UnexpectedTypeException!

Constants

Constants, declared with the const keyword, are named, immutable values that support all basic data types. These are useful for storing unchanging values that may be used repeatedly throughout code. Constants must be declared at the module or class level and cannot be declared within a function. It is important to note that with data structures like arrays, const works in a way similar to Java’s final keyword. For example, a const array prevents the array from being replaced by a new instance, but the elements of the array may be modified.

const PI = 3.14;
const EAT_BANANAS = true;
const BANANA_YELLOW = "#FFE135";

Symbols

Symbol objects are lightweight constant identifiers. When the Monkey C compiler finds a new symbol, it will assign it a new unique value. This allows symbols to be used as constants without explicitly declaring a constant:

using Toybox.System;

var a = :symbol_1;
var b = :symbol_1;
var c = :symbol_2;
System.println(a == b);  // Prints true
System.println(a == c);  // Prints false

Symbols are also useful as keys in data structures like dictionaries:

var person = {:title=>"George", :name=>"Taylor"};

One other important use for symbols is to reference method implementations for calls to Object.method() or when assigning callbacks with Method. In this instances, if a method myMethod{...} has been implemented, it can be referenced as a callbacks using the symbol :myMethod. See the section on Callbacks for more in-depth examples.

Enumerations

Enumerations are constant mappings from a Symbol to a Number value, created using the enum keyword. Unless explicitly set, the first symbol in an enumeration is assigned a value of 0, and each subsequent symbol is automatically assigned the value of the previous unassigned symbol plus one. Enumeration symbols can be used just like constants (that’s essentially what they are), and like constants, enumerations must be declared at the module or class level.

// Automatically incremented enumeration
enum {
    Sunday,     // 0
    Monday,     // 1
    Tuesday,    // 2
    Wednesday,  // 3
    Thursday,   // 4
    Friday,     // 5
    Saturday    // 6
}

// Enumeration initialized with an explicit starting value
enum {
    x = 1337,   // x = 1337
    y,          // y = 1338
    z,          // z = 1339
    a = 0,      // a = 0
    b,          // b = 1
    c           // c = 2
}

Arrays

Array objects are fixed-size, numerically indexed lists of objects. All members of an array do not need to be the same type of object. Like variables, arrays in Monkey C are typeless, so it is not necessary to declare an array’s type. There are two ways to create a new array:

// A new array with ten empty slots, initialized to 'null'
var myArray = new[10];

// A new five-slot array with assigned values
var myArray = [1, 2, 3, 4, 5];

Array elements are expressions, so it’s also possible to build multi-dimensional arrays:

var myArray = [[1, 2], ["one", "two"]];

Although Monkey C does not have a direct way of creating an empty, two-dimensional array, it can be done:

// Specify the array sizes
var first_dimension_size = 2;
var second_simension_size = 100;

// Create an empty one-dimensional array
var myArray = new [first_dimension_size];

// Initialize the sub-arrays to complete the two-dimensional array
for(var i = 0; i < first_dimension_size; i += 1) {
    myArray[i] = new [second_dimension_size];
}

Dictionaries

Dictionary objects, also called associative arrays or hash tables, are data structures similar to Array objects that map key-value pairs. Keys and values can be any type of Object, and each key-value pair does not need to be the same type combination within a given dictionary.

using Toybox.System;

var x = {};                                 // Declare a new, empty Dictionary
var myDictionary = { "a" => 1, "b" => 2 };  // Declare a new Dictionary with initialized values
myDictionary.put("c", "three");             // Add a new key-value pair with a String value
System.println(myDictionary["a"]);          // Prints "1"
System.println(myDictionary["c"]);          // Prints "three"
System.println(myDictionary["d"]);          // Prints "null" (there is no key "d")

The Object class has a built-in hashCode() method that automatically hashes (indexes) the keys added to a Dictionary. This provides an efficient way of looking up the arbitrarily ordered Dictionary values. Dictionaries automatically resize and rehash as items are added or removed, which makes them extremely flexible, but comes at a cost:

• Insertion and removal of Dictionary contents can cause performance problems if there is excessive resizing and rehashing
• Dictionaries are not as space-efficient as either Object or Array type objects because they require extra memory allocation space

The built-in hashCode() method is adequate in most cases, but if a custom Object type is used as keys in a Dictionary, it may be beneficial to override it to avoid index collisions and reduce lookup time:

class Monkey
{
    var mLengthInCentimeters;
    var mWeightInKilograms;

    initialize(length, weight) {
        mLengthInCentimeters = length;
        mWeightInKilograms = weight;
    }

    // Return a unique Number as the hash code for Monkey objects used as keys in Dictionaries.
    // For the record, this is a pretty terrible hashing function.
    function hashCode() {
        return (Math.pow(self.mLengthInCentimeters, self.mWeightInKilograms)).toNumber();;
    }
}

var rhesusMacaque = new Monkey(53.4, 7.7);
var capuchin = new Monkey(48.3, 4.2);
var mandrill = new Monkey(82.9, 32.3);

var monkeyContinents = {
    rhesusMacaque => "Asia",
    capuchin => "South America",
    mandrill => "Africa"
}

Flow Control

If Statements

In Monkey C, if statement are the most basic of the available flow control statements. They are used to execute a certain section of code only if a particular Boolean expression evaluates to true. The expression evaluated by the if statement cannot be an assignment. Values or objects that will evaluate to true include:

• A value of true
• A non-zero Number
• A non-null Object

As an example, this prints a message to the console when the value of result is greater than zero:

using Toybox.System;

var result = 5;
if (result > 0) {
    System.println("Result is greater than zero");
}

The else keyword can be added to an if block for more complex branching. Once an expression evaluates to true, its associated block of statements are executed and any remaining statements in the if block are skipped:

using Toybox.System;

var a = false;
var b = true;

if (a == true) {
    // 'a' is false, so this will not execute
    System.println("The variable 'a' is true!");
} else if (b == true) {
    // 'b' is true, so this block will execute
    System.println("The variable 'b' is true!");
} else {
    // Since the previous block has executed, this is skipped
    System.println("Neither is true!");
}

Statements may also be nested. In the example below, b and c are only evaluated if a is equal to 1:

using Toybox.System;

if (a == 1) {
    if (b == true) {
        System.println("The variable 'b' is true!");
    } else if (c == true) {
        System.println("The variable 'c' is true!");
    }
}

Lastly, Monkey C supports the ternary operator, which is a simple, alternative syntax for a basic if-else statement. The general form is:

var result = testExpression ? whenTrueExpression : whenFalseExpression

Where testExpression is evaluated to determine whether it is true, whenTrueExpression is the true result, and whenFalseExpression is the false result. The value of the resulting expression is assigned to the result variable. If resulting expression does not resolve to a value (e.g. something like a System.println() statement), the result variable is assigned a value of null.

// If 'a' is true, 'myValue' is assigned a value of 1; otherwise, it is assigned a value of 2.
var myValue = a ? 1 : 2;

Switch-Case Statements

A switch statement is another type of flow control statement that may have multiple execution paths rather than the single path offered by if statements. A switch statement first evaluates a condition, which must be an object—assignments are not allowed. Any number of successive case statements are allowed within a switch block, each followed by either an object or an instanceof expression. When the switch evaluation is either equal to or an instance of a case statement, the matching case block will execute. For example, these two examples function similarly:

using Toybox.System;

// An if-else block checking the myValue variable
if (myValue == 1) {
    System.println("The value is 1!");
} else if (myValue == 2) {
    System.println("The value is 2!");
} else {
    System.println("The value is not 1 or 2!");
}

// A switch-case block checking the myValue variable
switch (myValue) {
    case 1:
        System.println("The value is 1!");
        break;
    case 2:
        System.println("The value is 2!");
        break;
    default:
        System.println("The value is not 1 or 2!");
}

All statements following the matching case block, including subsequent case blocks, are executed in sequence until a break statement is encountered. At this point, the switch block terminates and the remaining case blocks are skipped. This behavior, called fall through, is illustrated below:

using Toybox.System;

switch (myValue) {
    case 1:
        System.println("The value is 1!");
        // Since there is no 'break', this will "fall through" and execute
        // the code in the next case block until its break statement is reached
    case 2:
        System.println("The value is 2!");
        break;
    default:
        System.println("The value is not 1 or 2!");
}

A switch block may also have a single, optional default case, which handles all cases not explicitly handled by one of the preceding case statements. A final break statement is not required because control flow will naturally fall out of the switch block at the end of the block, but it may be included if preferred.

Since switch statements can switch on objects or object types, it’s possible to perform more sophisticated actions. Below is a snippet of an app that receives an Ant payload that must be handled differently depending on how the message is coded:

var payload = message.getPayload();

switch (payload[MESSAGE_CODE_INDEX]) {
    case instanceof Number:
        System.println("Valid code!");
    case Toybox.Ant.MSG_CODE_EVENT_CHANNEL_CLOSED:
        // Open the channel
        ...
        break;
    case Toybox.Ant.MSG_CODE_EVENT_RX_FAIL_GO_TO_SEARCH:
        // Search for device
        ...
        break;
    case Toybox.Ant.MSG_CODE_EVENT_CRYPTO_NEGOTIATION_FAIL:
        // Data not encrypted, so handle appropriately
        ...
        break;
     case Toybox.Ant.MSG_CODE_EVENT_CRYPTO_NEGOTIATION_SUCCESS:
        // Data  encrypted, so handle appropriately
        ...
        break;
    case Toybox.Ant.MSG_CODE_EVENT_TX:
        // Update data and send out the next part of the message
        ...
    default:
        System.println("Invalid response!");
}

Deciding whether to use switch instead of if is often a matter of personal preference. In some cases, switch blocks may be more readable, particularly when there are a relatively large number of cases to consider. Fall through can also be a useful tool depending on the needs of a particular application.

Scoping in Switch Blocks

Variables declared within the switch block are scoped at the switch block level. Variables may also be enclosed by curly braces within a case block to limit scope to that case block. All variables defined at the switch block level must be initialized before being used in any subsequent case statements. For example:

switch (myValue) {
    case true:
        // Variable 'a' is scoped at the switch block level
        var a = 1;
    case 1:
        // Results in a compiler error because 'a' was not initialized in this case block
        var z = a;
        break;
    case "B": {
        // Variable 'a' is scoped at the code block level within the curly braces, so no scoping
        // conflict with 'a' at the switch block level
        var a = true;
        break;
    }
    case instanceof MyClass:
        // Results in a compiler error because 'a' has already been defined in the switch block
        var a = "Hello!"
    default:
        // No errors because 'a' was defined in the first case and initialized at the beginning of
        // the default case
        a = 0;
        var b = a;
}

Loops

Monkey C supports for, while, and do-while loops. Loops are used to repeat statements until conditions specified by an expression are met. All loops require braces enclosing their block of statements, and single-line loops are not supported.

The while and do-while loops have a familiar syntax:

// A do-while loop
var myCounter = 0;
do {
    // Do something
    myCounter++;
}
while (myCounter < 10);

// A while loop
myCounter = 0;
while (myCounter < 10) {
    // Do something
    myCounter++;
}

Monkey C allows variable declaration in for loops, which also have a familiar syntax:

var myArray = [1, 2, 3, 4, 5];
for (var i = 0; i < myArray.size(); i++) {
    // Do something until 'i' is greater than or equal to the array size
}

Flow control within loops can be managed by using the break and continue statements:

using Toybox.System;

// This for loop should only print the values 5, 6, and 7.
for (var i = 0; i < 10; i += 1) {
    if (i < 5) {
        continue;
    }
    System.println(i);
    if (7 == i) {
        break;
    }
}

Exception Handling

Monkey C supports structured Exception handling for non-fatal errors in the form of try-catch blocks:

try {
    // Attempt to execute this code
} catch (e) {
    // Catch and handle any exceptions thrown
}

Multiple catch statements are allowed to handle more than one possible exception type. When an exception is thrown, the first matching catch block will execute, and all subsequent catch blocks will be skipped (if a generic Exception handler is used, it’s a good idea to place last). An optional finally statement can be placed at the end of a try-catch block, which will execute regardless of whether an exception has been thrown.

try {
    // Attempt to execute this code
} catch (e instanceof MyExceptionClass) {
    // Catch and handle the MyExceptionClass exception
} catch (e) {
    // Catch all other exception types
} finally {
    // Execute this after the preceding try and catch statements are completed
}

To throw an Exception, use The throw keyword:

throw new Lang.Exception();

If an exception is not handled, an Unhandled Exception error will occur at runtime. The Connect IQ API throws exceptions in a few instances instances, such as SymbolNotAllowedException and UnexpectedTypeException. Refer to the API Documentation for more details about the various Exception types.

Functions

Functions (also called methods) are the meat_[2] of an application, defining discrete, callable units of code. They can exist in a class, module, or appear in the global module.

Defining a Function

Monkey C functions can take arguments, but because Monkey C is a dynamically typed language[1], argument types are not declared. Below is a simple function that takes a single ‘myValue’ argument and multiplies it by two:

function myFunction(myValue) {
    var result = myValue * 2;
}

Returning Values From Functions

It is not necessary to declare the return value of a function, thanks to dynamic typing, but all functions in Monkey C will still return a value. A return value may be specified with a return keyword:

function myFunction(myValue) {
    var result = myValue * 2;
    return result;
}

The return statement is optional, and if a function doesn’t have one, it will return a “garbage” value from the viewpoint of the caller.

Calling Functions

To use a function or a method, simply use the function call syntax:

// Call myFunction() and pass it an argument of '2', but do nothing with the result
myFunction(2);

// Call myFunction(), pass it an argument of '2', and assign the result to the 'myResult' variable
var myResult = myFunction(2);

It is also possible to call a function or method within another function or method:

function myOtherFunction() {
    var result = myFunction(2);
    // Do some other stuff with the result here
}

Classes and Objects

Classes are blueprints that bundle data and operations together into an instance of the class, called an object. Variables, functions, and other classes (often referred to as members) can be defined within a Monkey C class. Objects are compiled and cannot be modified at runtime, so all variables must be declared in either a local function, the class instance, or the parent module before they can be used.

Defining Classes

A class is defined using the class keyword. For example, here is a simple class that defines a circle with an mRadius member, representing the radius of a circle:

class Circle {
    var mRadius;
}

Creating Objects

To create an instance of a class, use the new keyword:

var myCircle = new Circle();

This doesn’t do too much that’s useful yet. However, when an object is instantiated with the new keyword, memory for the object is allocated and its initialize() method is automatically called, acting as a constructor. An initialize() method has been implemented in the Circle class below, which sets a radius value whenever a new Circle is created:

class Circle {
    var mRadius;
    function initialize(aRadius) {
        mRadius = aRadius;
    }
}

// Create a new circle with a radius of 2
var myCircle = new Circle(2);

If classes are nested, the outermost class must first be instantiated before and enclosed class may be instantiated.

Accessing Class Members

Within a method implementation, the current object instance can be referred to with either the self or me keywords. These may be used for disambiguating instance variables from local variables, or simply for clarity. For example, here’s the Circle class with new methods to calculate its circumference and surface area that use the self keyword to refer to the mRadius instance variable:

using Toybox.Math as Math;

class Circle {
    var mRadius;
    function initialize(aRadius) {
        mRadius = aRadius;
    }

    function getCircumference() {
        return 2 * Math.PI * Math.pow(self.mRadius, 2);  // 2*PI*r
    }

    function getArea() {
        return Math.PI * Math.pow(self.mRadius, 2);      // PI*r^2
    }
}

Inheritance

Inheritance allows one class to be based on another class, which helps speed development time and promotes code re-use. Instead of defining entirely new classes for similar objects, new classes can inherit members from existing classes. For example, a new Sphere class can be defined that shares a lot of the same characteristics of a circle by using the extends keyword to inherit from the Circle class:

using Toybox.Math as Math;
using Toybox.System as System;

class Circle {
    var mRadius;
    function initialize(aRadius) {
        mRadius = aRadius;
    }

    function getCircumference() {
        return 2 * Math.PI * Math.pow(self.mRadius, 2);   // 2*PI*r
    }

    function getArea() {
        return Math.PI * Math.pow(self.mRadius, 2);     // PI*r^2
    }

    function describe() {
        System.println("Circle!");
    }
}

class Sphere extends Circle {
    function initialize(aRadius) {
        Circle.initialize(aRadius);
    }

    // Notice Sphere has no getCircumference() method implemented here. Instead, it inherits the
    // getCircumference() method from the Circle class and may use it as if it were its own method.

    function getArea() {
        return 4 * Math.PI * Math.pow(self.mRadius, 2);  // 4*PI*r^2
    }

    function describe() {
        System.print("I'm a Sphere! My parent is a ");
        Circle.describe();
    }
}

The only thing not inherited from the parent class (also called a base class or superclass) is an initialize() method, which must be implemented separately for Sphere. In this case, it’s just calling the parent class’s initialize() method to set a radius.

The getArea() method from the Circle class won’t work for spheres, so a new getArea() method was also implemented to override the getArea() the method from the Circle class. Lastly, describe() methods were added to each class to let each object type describe itself. Let’s put these classes to work:

// Create new objects
var myCircle = new Circle(5);
var mySphere = new Sphere(5);

System.println(myCircle.getCircumference());  // 31.415928
System.println(myCircle.getArea());           // 78.539818
myCircle.describe();                          // "Circle!"

System.println(mySphere.getCircumference());  // 31.415928 (same as a circle of the same radius)
System.println(mySphere.getArea());           // 314.159271
mySphere.describe();                          // "I'm a Sphere! My parent is a Circle!"

Notice the describe() method from Sphere calls the parent’s describe() method directly using the parent class’s symbol. The superclass.memberMethod() is valid in Monkey C, but the superclass.memberVariable syntax is not supported.

Static Members

In some cases, certain class members need to be accessible within an object without creating an instance of an object. For example, imagine a unit conversion class that only contains unit conversion constants:

class Conversion {
    const FEET_PER_METER      = 3.28084;
    const MILE_PER_KILOMETER  = 0.621371;
    const TABLESPOONS_PER_CUP = 16;
    ...
}

var meters = 32;
var myConverter = new Conversion(); // Create an instance of the Conversion class
System.println(meters * myConverter.FEET_PER_METER + " feet"); // Prints "104.986877 feet"

Normally, it would be necessary to first create an instance of the Conversion class before using any of the members within the class, including variables, constants, enumerations, or functions. If the static keyword is applied to the constants, however, it’s possible to use them without instantiating the Conversion class:

class Conversion {
    static const FEET_PER_METER      = 3.28084;
    static const MILE_PER_KILOMETER  = 0.621371;
    static const TABLESPOONS_PER_CUP = 16;
    ...
}

var meters = 32;
System.println(meters * Conversion.FEET_PER_METER + " feet"); // Prints "104.986877 feet"

Another advantage to static members is that they belong to the class rather than to a particular instance of the class. This means that something like a static variable can be shared between mutliple instances of class, and if its value is changed in one instance, the new value is immediately available in all instances:

class BananaBunch {
    static var mNumberOfBananas = 10;
}

var bunchOne = new BananaBunch();
var bunchTwo = new BananaBunch();

System.println(bunchOne.mNumberOfBananas); // 10
System.println(bunchTwo.mNumberOfBananas); // 10

bunchOne.mNumberOfBananas = 12; // Change the value of the static variable

System.println(bunchOne.mNumberOfBananas); // 12
System.println(bunchTwo.mNumberOfBananas); // 12 - notice this one also reflects the change!

Data Hiding

Class members have three levels of access—private, protected, and public. The private modifier specifies that the member can only be accessed in its own class. The protected modifier specifies that the member can only be accessed by its own class or one of its subclasses. The hidden keyword is synonymous with the protected keyword. A public access modifier is the default, but it can also be explicitly specified. When the public access modifier is used for an enumeration, variable, or function, those members are visible to all other classes.

using Toybox.System as System;

class MyClass {
    protected var mVariable;
}

// This will produce a runtime error since it's trying to access a protected variable from myClass
function myFunction() {
    var myObject = new MyClass();
    System.println(myObject.mVariable);
}

Variables that are public or protected may be accessed using either one of the following formats:

var x = mMmemberVariable;
var y = self.mMemberVariable;

Instanceof and Has

Monkey C provides two operators to do runtime type checking that need some special attention: instanceof and has. Monkey C’s object-oriented design patterns in conjunction with the has and instanceof operator enables software that has implementations for many devices in a single code base.

The instanceof operator checks whether an object instance inherits from a given class:

using Toybox.System;

var value = 5;
if (value instanceof Lang.Number) {
    System.println("Value is a number");
}

The has operator checks whether a given object has a particular symbol, which may be a public method, instance variable, or even a class definition or module. For example, accelerometer data is available in Sensor.Info, but not all products have an accelerometer. Attempting to use this data on certain products may cause the app to crash with a Symbol Not Found error. To avoid this, the has operator can be used to check for accelerometer support:

using Toybox.Sensor as Sensor;

var sensorInfo = Sensor.getInfo();
if (sensorInfo has :accel && sensorInfo.accel != null) {
    var accel = sensorInfo.accel;
    var xAccel = accel[0];
    var yAccel = accel[1];
    System.println("x: " + xAccel + ", y: " + yAccel);
}

Callbacks

Functions in Monkey C are not first class, so cannot be passed as arguments to other functions to be used as callbacks. Since functions are bound to the object in which they are created, Method objects must be used to create callbacks.

One approach is to use a combination of a function and its object instance:

class MyClass {
    function operation(a, b) {
        // The code here is really amazing. Like mind blowing amazing.
    }
}

function myFunction() {
    var myObject = new MyClass();                // Create a new instance of MyClass
    var myMethod = myObject.method(:operation);  // Get a callback for the "operation" method from myObject
    myMethod.invoke(1, 2);                       // Invoke myObjects's "operation" method
}

Unlike classes, modules do not inherit from Object so do not have access to the method() function. However, a new instance of Method can be created, which allows module-level functions to be invoked as callbacks in a similar fashion:

using Toybox.Lang as Lang;

module MyModule
{
    function operation() {
        // Some more amazing code. Only an infinite number of monkeys typing randomly over an
        // infinite period of time could write something this good.
    }
}

function myFunction() {
    var myMethod = new Lang.Method(MyModule, :operation);
    myMethod.invoke();
}

A Method object will invoke a method on the instance of the object it came from, and keeps a strong reference to the source object.

Weak References

Monkey C is reference counted, which means the runtime system will free memory when the number of objects referencing that memory decrements to zero. Reference counting allows memory to become available very quickly, which is important in low memory environments. The kryptonite of reference counting are circular references. A circular reference happens when a cycle is formed in the reference chain. For example, imagine that object C references an object A, while object A references object B and object B references object A:

After a while, C gets invited to sit at the cool-kid table, so it dereferences A to go hang out with its real friends:

The memory for A and B should be freed at this point, but A and B both have a reference count of one because they reference each other. The memory used by A and B are now unavailable to objects from the cool-kids table, which is generally not a good thing. However, sometimes A and B really do need to reference each other. In these cases, you can use a weak reference, which keeps a reference to an object but does not increment the reference count. This means the object reference can be destroyed, and is a case that should be handled.

To create a weak reference, use the weak() method, an Object method available to all Monkey C objects.

// We would make a "Hans and Franz" reference here but certain advertising has probably made them uncool.
var weakReference = myObject.weak()

If calling weak() on one of the immutable types (Number, Float, Char, Long, Double, String), then it returns the object itself. Otherwise, it will return a WeakReference instance. Weak references have a stillAlive() method to check if a weak reference is still valid, and have a get() method to create a strong reference to an object:

if (weakReference.stillAlive()) {
    var strongReference = weakReference.get();
    strongReference.myMethod();
}

Remember to only keep the strong reference within the needed scope!

Modules

Monkey C modules serve a purpose similar to Java packages, but can contain variables, functions, classes, and other modules:

module MyModule
{
    class MyClass {
        var mValue;
    }
    var moduleVariable;
}

function myFunction() {
    MyModule.moduleVariable = new MyModule.MyClass();
}

It is common for static methods to exist at the module level instead of belonging to a particular class. Unlike classes, however, modules have no concept of inheritance or data hiding (the extends and hidden keywords are not supported for modules).

Using Statements

Modules can be imported into another class or module with the using keyword, scoping the module to the class or module in which they are defined.

using Toybox.System;

function myFunction() {
    System.print("Hello");
}

Modules may also be assigned an alias with the as clause, useful for shortening module names or when a different naming scheme is preferred:

using Toybox.System as Sys;

function myFunction() {
    Sys.print("Hello");
}

Once imported, all classes inside a module must be referenced through their parent module.

Scoping

Monkey C is a message-passed language. When a function is called, the virtual machine searches a hierarchy at runtime in the following order to find the function:

1. Instance members of the class
2. Members of the superclass
3. Static members of the class
4. Members of the parent module, and the parent modules up to the global namespace
5. Members of the superclass’s parent module up to the global namespace

The code below illustrates:

using Toybox.System;

// A globally visible function
function globalFunction() {
    System.println("This is the global function!");
}

module Parent
{
    function parentFunction() {
        System.println("This is the parent's function!");
        globalFunction();  // May call a globally visible function
    }

    class Child {
        function childFunction() {
            System.println("This is the child's function!");
            globalFunction();       // May call a globally visible function
            parentFunction();       // May call a function in our parent module
            staticChildFunction();  // May call a static function within the class

        }

        static function staticChildFunction() {
            System.println("This is the child's static function!");
            globalFunction();  // May call a globally visible function
            parentFunction();  // May call a function in our parent module
            // Static methods can't call instance methods (childFunction) but still have access to parent modules!
        }
    }
}

In some cases, it may be more efficient to search from the global namespace instead of the current scope with the bling symbol $, which refers to the global scope:

using Toybox.System as System;
function myFunction() {
    System.println("Hello Hello");
}

class MyClass {
    function myFunction() {
        System.println("Every time I say goodbye you say hello");
    }

    function() {
        $.myFunction();  // Call the global myFunction()
        myFunction();    // Call the instance myFunction()
    }
}

Using bling can improve runtime performance when referring to a global variable. Because Monkey C is dynamically typed, referencing a global variable will search your object’s inheritance structure and the module hierarchy before it will eventually find the global variable. Instead, we can search globals directly with the bling symbol:

using Toybox.System as System;

var familyFortune = "There's always money in the banana stand.";

module BluthCompany
{
    class BananaStand {
        function getMoney() {
            // At runtime, the VM will search:
            //   1. The BananaStand
            //   2. The BananaStand's superclass, Toybox.Lang.Object
            //   3. The BluthCompany module
            //   4. The BluthCompany module's parent globals
            // ...and finally finds the family fortune!
            System.println(familyFortune);

            // This will search only the global namespace for the family fortune. Thanks bling!
            System.println($.familyFortune);
        }
    }
}

While Monkey C will normally search the entire object hierarchy for an object, when the bling symbol is used, only the global space is checked. If nothing is found there, the virtual machine will not traverse back down the object hierarchy looking and will instead return a Symbol Not Found error.

Annotations

Monkey C allows associating symbols with class or module methods and variables. Annotations are used to communicate additional intentions to the compiler, and are sometimes used to add new features without changing the Monkey C grammar. For example, Run No Evil tests require annotations to demark sections of code that are meant only for testing:

// A test class containing a Run No Evil test method denoted by (:test)
class TestMethods {
    (:test)
    static function testThisClass(x)
}

The following annotations have special meanings to the Monkey C compiler:

:background

Denotes code blocks available to the Background process.

:debug

Code blocks decorated with this annotation will not be included in release builds at compile time.

:release

Code blocks decorated with this annotation will not be included in debug builds at compile time.

:test

Denotes code blocks available to the Test module for Run No Evil tests

For reference, annotations are written into the debug.xml file generated in a project’s ‘bin’ directory by the compiler when a project is built.

Jungle Reference Guide

Welcome to Jungles[3], the build language for Connect IQ apps. This guide will cover the following topics:

• The syntax of the jungle build language
• Using build exclusions to tailor your apps at build time
• Managing monkey barrels
• Using Jungles with Visual Studio Code or from the command line

Jungle Syntax

Jungle files contain build instructions that are made up of qualifiers, local variables, and values. Jungle files may also contain comments. Each build instruction is made up of qualifier-value or variable-value pairs separated by an equal sign (=), and terminate with a new line character.

Qualifiers are analogous to the device and family qualifiers described in the previous section. They are treated as reserved words, can only be set equal to other qualifiers, and are globally scoped. Qualifiers and their properties can be used with the dereference operator $(VAR) and are evaluated after all Jungle files for a project have been processed.

Project Qualifiers

Project qualifiers specify global information that applies across the project. Project qualifiers have x properties that can be referenced by following project with a dot (.) and a property name:

Device Qualifiers

Device qualifiers have six properties that can be referenced by following a qualifier with a dot (.) and a property name:

Local Variables

Variables are a convenient way of re-using values, such as long path strings. Unlike qualifiers, local variables have no properties, cannot be set equal to a qualifier, and are locally scoped. Variables can be used with the dereference operator $(VAR) and are evaluated after the Jungle file in which they are defined has been processed.

Values

Values are a list of one or more string values that represent the value of a particular qualifier, qualifier property, or local variable. Multiple list items are separated by semicolons (;).

Comments

Lines preceded with a hash mark (#) are treated as comments and are ignored by the compiler.

A basic Jungle file build instruction will use this pattern (comments are optional):

# This is a comment
qualifier[.property] = value

Jungle files must be named with a .jungle extension, and are kept in the root of the Connect IQ project.

Note: Dereferenced qualifiers are evaluated “lazily”, which means that when building for a specific device, all qualifiers and properties are resolved for that device after all Jungle files are processed, while local variables will be resolved after processing the Jungle files in which they are defined. The exception to lazy evaluation is when a qualifier or local variable is dereferenced when setting that qualifier or variable, in which case the qualifier or variable is evaluated during Jungle file processing.

Sources and Resources

Setting source and resource paths are a common use for Jungles. In addition to tailoring source code and resources to particular devices to improve user experience, it can also help with memory management since only the sources defined in the Jungle file are compiled into the executable.

As a practical example, assume an application will use a shared set of resources for fēnix devices contained in a fenix-resources directory at the root of the project. Since these products are not all in the same families, a custom Jungle file must be written to tell the compiler these devices should use this shared resources folder. We can start by setting the resource path for fēnix 5:

# Set the fenix 5 resource directory
fenix5.resourcePath = $(fenix5.resourcePath);fenix-resources

Let’s break this down a little:

fenix5.resourcePath

The device qualifier for the fēnix 5 defined in the default Jungle file followed by the resourcePath property

$(fenix5.resourcePath);

The original value of the fenix5.resourcePath property, accessed with the dereference operator $(VAR).

The default Jungle file defines the base resource path as the resource directory in the root of the project, and all devices inherit this. It also defines device-specific and family-specific resource directories that can be used implicitly in any project. Including this in the resource path ensures that the device can still look in these directories for resources if required resources aren’t found in more device-specific locations. If this is omitted, it would tell the compiler to only look for fenix 5 resources in the fenix-resources directory.

fenix-resources

The shared directory we want to add as a resource location for the device.

If this looks familiar, it’s because it’s pretty similar in concept to setting PATH environment variables. Path precedence goes from left to right in Jungle files, so the compiler will process inherited resources first before processing resources found within ‘fenix-resources’, which can potentially override resources already defined. Adding the fenix-resources directory to other fēnix devices just requires similar instructions for each additional device:

# Set the fenix 5 resource locations
fenix5.resourcePath = $(fenix5.resourcePath);fenix-resources

# Set the fenix 3 resource locations
fenix3.resourcePath = $(fenix3.resourcePath);fenix-resources
...

Setting source paths works in essentially the same way, allowing apps to selectively include specific source code on a per-device or per-device family basis. As an example, consider an app that has common code shared by all products in the source folder and product-line specific source code in other folders: wearable-source for wearable devices, edge-source for bike computers, and handheld-source for handheld mapping units. The following demonstrates how to use a jungle to configure this project:

# Reset the base source path to include only source files in the source folder. The
# default source path includes source files in the project folder and all subfolders.
base.sourcePath = source

# Set the source path for wearable devices by device family
round.sourcePath = $(round.sourcePath);wearable-source
semiround.sourcePath = $(semiround.sourcePath);wearable-source

# Set the source path for edge devices by device
edge530.sourcePath = $(edge530.sourcePath);edge-source
edge830.sourcePath = $(edge830.sourcePath);edge-source
edge1030.sourcePath = $(edge1030.sourcePath);edge-source

# Set source path for handheld devices by device
gpsmap66.sourcePath = $(gpsmap66.sourcePath);handheld-source
oregon7xx.sourcePath = $(oregon7xx.sourcePath);handheld-source
rino7xx.sourcePath = $(rino7xx.sourcePath);handheld-source

Localization Resources

Localization strings are a kind of resource in Connect IQ, but have a slightly different syntax since multiple languages may be supported by a single device or device family. Suppose an application supports both English and Spanish, and all of the fēnix English localization resources are stored in a fenix-resources-eng directory, while the Spanish localization resources are kept in a fenix-resources-spa directory.

# Set the fenix 5 English language resource location
fenix5.lang.eng = $(fenix5.lang.eng);fenix-resources-eng

# Set the fenix 5 Spanish language resource location
fenix5.lang.spa = $(fenix5.lang.spa);fenix-resources-spa

# Set the fenix 3 English language resource location
fenix3.lang.eng = $(fenix3.lang.eng);fenix-resources-eng

# Set the fenix 3 Spanish language resource location
fenix3.lang.spa = $(fenix3.lang.spa);fenix-resources-spa
...

The lang qualifier property is used in this build instruction to specify that a localization resource is being set, and is followed by an additional ISO 639–2 language code localization qualifier to indicate for which language the supplied resource locations are intended. A list of supported localization qualifiers can be found in the Strings section. Specifying an unsupported localization qualifier will result in an error at compile time.

When specifying localization resources within Jungle files, the supported languages must also be set in a project’s manifest, otherwise the associated localization overrides will be ignored.

Excluded Annotations

In some cases, there are specific modules, classes, methods, or variables that should only be used by a subset of devices, but excluding an entire source file is excessive. The excludeAnnotations qualifier property allows build instructions to specify specific annotations that will be excluded when an application is built. This may help save memory during app execution on a device.

A common reason for excluding source is when an application uses one algorithm that takes advantage of the latest APIs on newer devices, but must use a simpler algorithm on older devices that don’t have the latest APIs available. For example, the following example shows an app that has two methods—one that uses the newer Sensor.AccelerometerData, and one that relies on Sensor.Info.accel data:

import Toybox.WatchUi;

const experimental = Toybox.Sensor has :AccelerometerData;

class MyAmazingAppView extends WatchUi.View {

    function onUpdate(dc) {

        sharedLogic();

        if (experimental) {
            // If a newer device, call the new logic
            newHotnessLogic();
        } else {
            // If an older device, call the old logic
            oldAndBoringLogic();
        }
    }

    function newHotnessLogic() {
        // Advanced functionality using Sensor.AccelerometerData
    }

    function oldAndBoringLogic() {
        // Basic functionality using Sensor.Info.accel data
    }

    function sharedLogic() {
        // Shared logic
    }
}

This will function properly as-is, but all of the code is included regardless of the build target. If the app is approaching memory limits, it may be useful to exclude the unused method, especially if the method is sufficiently large and impacts available memory. To do this, set the excludeAnnotations qualifier property in the Jungle file to the appropriate annotation value:

# By default, exclude the new, experimental logic
base.excludeAnnotations = experimental
# Exclude the old, boring logic from fenix 5
fenix5.excludeAnnotations = boring

Then, update the application to use annotations:

import Toybox.WatchUi;

(:boring) const experimental = false;
(:experimental) const experimental = Toybox.Sensor has :AccelerometerData;

class MyAmazingAppView extends WatchUi.View {

    function onUpdate(dc) {
        // If a newer device, call the new logic
        // otherwise, call the old logic
        myAlgorithm();
    }

    (:experimental)
    function myAlgorithm() {
        sharedLogic();
        if (experimental) {
            newHotnessLogic();
        } else {
            throw new MyException("Toybox.Sensor.AccelerometerData not supported!");
        }
    }

    (:boring)
    function myAlgorithm() {
        sharedLogic();
        oldAndBoringLogic();
    }

    (:experimental)
    function newHotnessLogic() {
        // Advanced functionality using Sensor.AccelerometerData
    }

    (:boring)
    function oldAndBoringLogic() {
        // Basic functionality using Sensor.Info.accel data
    }

    function sharedLogic() {
        // Shared logic
    }
}

Monkey Barrel Management

Barrels can also be added manually to the project’s main Jungle file using the barrelPath qualifier property:

# Include all the Barrels from the 'barrels' directory at the root of the project
base.barrelPath = barrels

# Include a specific Barrel from the 'barrels' directory
base.barrelPath = barrels/IconLibrary.barrel

# Include multiple, specific Barrels from the 'barrels' directory
base.barrelPath = barrels/IconLibrary.barrel;barrels/GraphLibrary.barrel

It’s also possible to use the annotations qualifier property to import select, annotated portions of a barrel. This is useful when a Barrel contains a library of classes and methods, but an application only needs to use a fragment of the library. For example, assume the GraphLibrary barrel imported above contains several different graphing methods, but an application only needs to use a bar graph. The Barrel author was kind enough to annotate each method, so rather than using the entire Barrel, we can limit imported code to only those methods that are needed:

# Import the 'bar' annotated method from the GraphLibrary Barrel
base.GraphLibrary.annotations = bar

In order for the compiler to correctly resolve Monkey Barrels, Barrel dependencies must also be added to the project’s manifest file:

<iq:barrels>
    <iq:depends name="IconLibrary" version="0.0.0"/>
</iq:barrels>

Once completed, the specified Barrels will be available for use in a project.

Defining Project Dependencies

What if a quick change is made to a developer’s barrel code in the development process of a dependant application? It would be cumbersome to export a barrel and update the dependencies in the manifest.xml every time the code is changed in the Barrel project. Connect IQ application projects can have direct Monkey Barrel project dependencies removing the need for these steps.

Adding a Barrel project dependency is done by specifying the Jungle file or files of the project or projects depended upon within the barrelPath. Jungle files can be specified individually or grouped in the barrelPath.

For example, a developer is creating an application, but she wants to include a standard set of icons that define her brand. She realizes in development that she needs to add a few more icons and decides to finally create that super specialized function that she is always needing. She can work dynamically on both projects and link her application project to her Barrel code by adding the Barrel project’s Jungle file to the barrePath like this:

# Include a specific Barrel project
base.barrelPath = MyIconBarrel/MyIconBarrel.jungle

Another developer is working on a math intensive application. Thankfully, someone has created an extensive MathLibrary Barrel that he has pulled in. He also has a local MyIconLibrary Barrel project with some standard icons. He has a set of icons for round devices defined in a roundIcons.jungle file that he wants to use in his application. He includes both the packaged MathLibrary.barrel and his own roundIcons defined in his local barrel project like this:

# Include a specific Barrel from the 'barrels' directory and a Jungle from a Barrel project
base.barrelPath = barrels/MathLibrary.barrel;MyIconBarrel/roundIcons.jungle

Our second developer realizes that he wants to support rectangle devices as well. These have been defined in a rectangleIcons.jungle. He includes multiple build instructions from MyIconBarrel by grouping the Jungle files in square brackets [] like this:

# Include a specific Barrel from the 'barrels' directory and multiple Jungles from a Barrel project
base.barrelPath = barrels/MathLibrary.barrel;[MyIconBarrel/roundIcons.jungle;MyIconBarrel/rectangleIcons.jungle]

Take a look at the [Monkey Barrels](./CoreTopics.html Libraries#shareablelibraries) chapter to learn more about Monkey Barrels and how they can be used.

The Default Jungle File

The Connect IQ SDK includes a default Jungle file, which is always applied to projects even if no custom Jungle files are present. It defines a base qualifier, which represents all source files (.mc) contained in the project, and all resource files found in the resources at the root of a Connect IQ project. It also defines default device, family, and language qualifiers that are the basis for the qualifier scheme described in the previous section.

When a project is built, the instructions from the default Jungle file are applied first, then any instructions from custom Jungle files are applied. This makes it possible for customizations to override the default build instructions.

Using Jungles with Visual Studio Code

By default, each project is configured to look for a monkey.jungle file in the root of the project and will use it if it exists. However, if a project is organized differently or a different Jungle file name is preferred, the Jungle file location can be set easily by going to File > Preferences > Settings and editing the Monkey C settings:

Using Jungles from the Command Line

For those who prefer to use the monkeyc shell command to build projects rather than Visual Studio Code, the -f option is required and accepts a list of Jungle files, separated by semicolons (;) or colons (:):

monkeyc -o myApp.prg myApp.mc -d fenix5 -f monkey.jungle;monkey2.jungle

In lieu of this new option, the -z option to specify resource paths, the -x option to specify build exclusions, the -m option to specify the manifest file, and the ability to specify source paths have been deprecated and will be removed in a future SDK release. Here is a general description of how this will work:

• When specifying a Jungle file with the -f option, the default Jungle file will first be applied to the project before the specified Jungle file is applied
• If more than one Jungle file is provided after the -f option, precedence will be given to the build instructions in the last Jungle file in the list
• If no resource or source options are specified, either as a Jungle file the compiler will attempt to apply the default Jungle file to the project
• Use of both the -f option and any deprecated options in combination is not allowed and will cause a compiler error

The manifest file of the project must be specified within a Jungle file passed at the command line and any Jungle can contain this specification. Here is what it looks like:

project.manifest = manifest.xml

There can be only one[4] manifest file defined within the set of jungle files provided. When relative paths are used within a jungle file the path will be resolved against the Jungle file’s parent directory. Relative paths within the default.jungle are resolved against the parent directory of the manifest file that is found.

Note: Legacy projects using -m, -x, -z, and/or supplying source files at the command line will result in a compiler warning.

Monkey Motion

The Monkey Motion UI tool or the command line can be used to import your animations.

Using the Monkey Motion UI

To use the Monkey Motion tool’s user interface, launch the executable, monkeymotion (Windows/Linux) or monkeymotion.app (Mac), either from the command line or using the Visual Studio Code Monkey C extension with the Monkey C: Open Monkey Motion command from the command palette.

When initially launched, the tool will populate a list of devices that support Connect IQ Animations:

The developer can then select which devices to encode an animation for. A Connect IQ project manifest file can be loaded into the tool if the developer prefers which causes the tool to mark any devices that are both supported by the project as well as that support Connect IQ Animations as selected. If a developer wishes to tweak the file encoding to use something other than the default settings, the advanced tab offers more options:

The Monkey Motion tool generates a Monkey Motion Manifest (or .mmm) file for each animation processed. The manifest will contain mappings between a device and a Monkey Motion (or .mm) file containing the binary of the encoded file. It is possible for a single animation to produce multiple .mm files since different encodings will be created based off of a video’s target resolution and the bits per pixel of the device.

In addition to generating encodings of the input, the tool can be used for scrubbing the encoded animation:

If the developer wishes to scrub a previously encoded animation, the File menu option can be used to select Load Animation, which accepts Monkey Motion Manifest files as input.

Using the Command Line

Videos can also be encoded at the command line using the monkeym script. The following options are available at the command line:

Considerations

The Monkey Motion tool offers several advanced settings options, which introduce multiple areas of consideration. This section offers developers a few tips, case studies, and generally more in-depth information with the intention of them finding the most beneficial video encoding configurations.

Image Quality Considerations

Specifying an image quality value of 3 provides lossless compression (lossless in the sense that the encoder always uses the closest color available in the palette for each pixel), whereas specifying a value of 2 or 1 may allow further compression at the expense of making color substitutions which allow for better compression (lossy).

Frame Rate Considerations

The maximum frame rate of an animation is limited by both decoding time, which increases with higher compression, and by the amount of motion in the input video.

Note: Because Connect IQ devices do not support vertical synchronization, high frames rates could potentially result in screen tearing.

Compression Level Impact

Compression level effects both compression and decoding overhead. Videos where the majority of the frame does not change from frame to frame can benefit from higher compression levels such as 9 without much consideration to the performance impact. For videos with lots of motion all over the screen, selecting a higher compression level may cause slower playback (due to the extra overhead necessary to decompress). For reference, this is a table showing the correlation between compression level and decoding time of a GIF file (with a high degree of complexity) running on the Fēnix 5 Plus:

At the same time, it is possible in some cases of these high motion, hard to compress videos that using a lower compression level may actually result in a smaller file size. For reference, this is another table showing the correlation between compression level and decoding time of a different GIF file (again with a high degree of complexity) running on the Venu:

The compression level of 6 actually produces the smallest file size. However, in this scenario, it would be better to accept the negligible size increase and use the compression level 1 because the decoding overhead would be much less. When in doubt about trying to get the maximum frame rate for a high motion video, a developer should start at compression level 1 and work their way up (knowing it may make the frame rate / size worse).

Note: The decoding time on high color resolution devices can potentially be affected more dramatically.

Complexity Level Impact

Like the video compression level, the complexity of the video also has a direct impact on animation file size, as well as decoding performance. The complexity is determined by both the variations within the same frame and the variations among successive frames.

For reference, sample GIF files were encoded for the Fēnix 5 Plus using a compression level of 5 to test the complexity impact.

Low Complexity

Frame Count: 30
Monkey Motion File Size: 107 KB
Average Frame Decoding Time: 8 ms

Medium Complexity

Frame Count: 25
Monkey Motion File Size: 412 KB
Average Frame Decoding Time: 26 ms

High Complexity

Frame Count: 24
Monkey Motion File Size: 758 KB
Average Frame Decoding Time: 39 ms

Color Depth for AMOLED Devices

AMOLED devices use the RGB565 color format, i.e., red / blue can never exceed 5 bits per pixel. Specifying the value of 5 for AMOLED devices, which will reduce green from 6 to 5 bits per pixel, could potentially result in improving the animation’s compression without causing a visually noticeable difference considering the 256 color palette restriction.

Memory Impact

Each animation is considered a rendering layer. When an animation is added to a View, it will be assigned a frame buffer (in the form of a BufferedBitmap), which is worth a single frame of raw pixel data. For example, if the color depth is 8 bits, then a 240x240 animation will take roughly 58 KB (240 x 240 x 1) of memory out of the Connect IQ app memory budget.

Overlay Frame Memory

In the context of a View with animations, native drawables added to a View are grouped into a single layer, known as the “overlay” layer. The overlay frame is needed to ensure a smooth playback experience and will only be created on demand. Currently, the overlay buffer takes a full screen’s worth of memory from the app memory budget (in the form of a BufferedBitmap, like animations).

Case Studies

For reference, these tables show the memory impact of animations played on the Fēnix 5 Plus, which has a 240x240 screen resolution and 8bpp color depth.

A View with two animations and no native drawables:

Total: 60 KB

A View with two animations and native drawables:

Total: 118 KB

Monkeygraph Reference

We can use the Monkeygraph tool to create a preview of data recorded in . The Monkeygraph tool requires the following:

1. A FIT file with the recorded developer data
2. An IQ file of the app (you can acquire an IQ file via the [App Export Wizard]).

The tool will allow you to test how charts will look before uploading your app for review.

There are two ways that you can use the Monkeygraph tool included with the SDK:

Launching the Monkeygraph tool in Visual Studio Code:

1. Summon the command palette
2. Select Monkey C: Open Monkey Graph

This launches a new window for the Monkeygraph tool.

Launching the Monkeygraph tool with the command line:

You can start the Monkeygraph tool with following from the command line:

$ monkeygraph

Using the Monkeygraph tool:

1. Click on “File”

1. Click “Open IQ File”
2. Select the IQ File generated from your project
3. Click “Open FIT File”
4. Select the Fit file with the recorded developer data

A new view will launch a graph showing the data:

And here we see some secondary data on another page:

Monkey C Visual Studio Code Extension

The Monkey C extension adds support for using the Connect IQ SDK, including a syntax highlighting editor, build integration, and integrated debugger. The Monkey C extension requires Visual Studio Code, the Oracle Java™ Runtime Environment 8 (version 1.8.0 or higher) and Connect IQ SDK version 4.0.6 or higher.

This Monkey C extension offers several features, including:

• Real-Time Errors and Warnings – These will display when editing Monkey C, Jungle, Settings, MSS and Resource XML files. Any reported errors or warnings will display in the Problems tab.
• Autocompletion – When editing Monkey C, Jungle and MSS files, autocompletion suggestions will be based on the detected scope. In the Monkey C editor, you can autocomplete functions with argument and type information by autocompleting the function keyword in a class or module.
• References – You can find all references of any class or module member by right-clicking on it and selecting “Find all References” from the context menu. You can also search for a symbol in the document by summoning the command palette and typing @symbol name or search the entire workspace by summoning the command palette and typing #symbol name.
• Hovering – See type information about a variable, function name, class or module by hovering the mouse over the symbol in question.
• Go to Definition – You can jump to the definition of any class or module member by selecting “Go to Definition” from the context menu.
• Folding Ranges – Comments, imports and regions of code can now be folded.

To fully take advantage of these features, your project needs to have a type check level of gradual or higher. Real time errors will be for the last device the project was built for, or the first product in the manifest if no product has been built during your current session.

Installing the Monkey C Extension

1. In Visual Studio Code go to the View > Extension
2. In the Extensions Marketplace search box type “Monkey C”
3. Select the Monkey C extension from Garmin
4. Use the Install button to install the extension in Visual Studio Code. This will require a restart of Visual Studio Code.
5. After Visual Studio Code restarts, summon the command palette with Ctrl + Shift + P (Command + Shift + P on Mac)
6. Type “Verify Installation” and select Monkey C: Verify Installation

Project Management

The following commands can be used to create a new project and export it:

Manifest Editing

The following commands can be used to edit and update the manifest.xml of your project:

Interfacing with the Connect IQ SDK

The following commands allow you to access the SDK tools and documentation from Visual Studio Code:

Running the Program

Before running the program, make sure you have one of your source files (In the source folder with the .mc extension) open and selected in the editor.

1. Select Run > Run Without Debugging (Command + F5 on Mac, Ctrl + F5 on other platforms)
2. You will be prompted with the list of products your application supports. Select one from the list.

If all goes well, the simulator will start up and the selected watch will appear:

Running Run No Evil Tests

You can use the following commands to run tests:

Editing the Launch Configuration

The extension will create a launch.json for your project when you run or debug your product. The launch.json provides many customization options for adding launch functionality

Using Monkey C from the Command Line

Before getting started with the installation on Mac or Windows, you’ll need Oracle Java™ Runtime Environment 8 (version 1.8.0 or higher) installed. Once that’s done, continue on to your platform’s installation instructions.

OS X Installation

1. Install the Connect IQ SDK manager, download the SDK, and set the active SDK.
2. Point your PATH to the active Connect IQ bin directory in the Terminal. To temporarily add it to a single local shell instance:

$ export PATH=$PATH:`cat $HOME/Library/Application\ Support/Garmin/ConnectIQ/current-sdk.cfg`/bin

For a more persistent addition, open .bash_profile in a text editor:

$ touch ~/.bash_profile
$ open ~/.bash_profile

Then add the line below to the file and save the changes:

export PATH=$PATH:`cat $HOME/Library/Application\ Support/Garmin/ConnectIQ/current-sdk.cfg`/bin

Windows Installation

1. Install the Connect IQ SDK manager, download the SDK, and set the active SDK.
2. Point your PATH to the active Connect IQ bin directory in the command prompt:

> for /f usebackq %i in (%APPDATA%\Garmin\ConnectIQ\current-sdk.cfg) do set CIQ_HOME=%~pi
> set PATH=%PATH%;%CIQ_HOME%\bin

Linux Installation

1. Install the Connect IQ SDK manager, download the SDK, and set the active SDK.
2. Point your PATH to the active Connect IQ bin directory in the command prompt:

$ export PATH=$PATH:`cat $HOME/.Garmin/ConnectIQ/current-sdk.cfg`/bin

For a more persistent addition, open .bash_profile in a text editor:

$ touch ~/.bash_profile
$ nano ~/.bash_profile

Then add the line below to the file and save the changes: CTRL-X

export PATH=$PATH:`cat $HOME/.Garmin/ConnectIQ/current-sdk.cfg`/bin

Basic Commands

After installation, three new shell commands are available: connectiq, monkeyc, and monkeydo.

• connectiq launches the Connect IQ simulator, which can be used to run and test apps on your computer before running them on your device. In the simulator, your app will only have access to those APIs that are available on the currently simulated device. For example, an API only available in Connect IQ v2.2.x or higher, such as PersistedContent, will not be available on devices that run earlier versions of Connect IQ.

• monkeyc calls the Monkey C compiler. The compiler can take code from multiple files and link them together into a single Connect IQ executable (a PRG file). The usage is:

> monkeyc [-d <arg>] [-f <arg>] [-o <arg>] [-y <arg>]

Note: For more information on all the command line options, refer to the Compiler Options section in the Monkey C guide.

• monkeydo runs a Connect IQ executable in the simulator. You must have previously started the simulator with connectiq. The usage is:

monkeydo [executable] [device_id] [-t | -t test_name]

Here is an example of a basic build and run cycle from the command line:

// Launch the simulator:
> connectiq

// Compile the executable:
> monkeyc -d fenix5plus -f /path/to/monkey.jungle -o project_name.prg -y /path/to/Dev_Key

// Run in the simulator
> monkeydo myApp.prg fenix5plus

Note: For more information on the -f option and the Jungle build framework, see the Overriding Resources section of this guide.

Generating a Key Using OpenSSL

If you’re working from the command line you can generate a RSA key using OpenSSL. The following command will generate a valid signing key.

> openssl genrsa -out developer_key.pem 4096
> openssl pkcs8 -topk8 -inform PEM -outform DER -in developer_key.pem -out developer_key.der -nocrypt

This developer key, developer_key.der, is passed to the compiler using the -y command line option.

Title: Connect IQ User Experience Guide Author: Garmin International Date: March 04, 2025 CSS: resources/programmers-guide/style.css Copyright: Copyright 2015–2025 Garmin, International.

Device Reference

Note: All button functions listed are available in the simulator. For non-touch devices without a dedicated “Menu” button it may be necessary to press and hold the middle button on the left to access the menu. For the Edge® 520 there is a shared “Enter/Menu” button that behaves in much the same way.

Approach® S50

App Types

1 Field Layout

2 Fields Layout

3 Fields Layout

4 Fields Layout

Part Number 006-B4656–00

Languages

ara, bul, ces, dan, deu, dut, eng, est, fin, fre, gre, heb, hrv, hun, ind, ita, lav, lit, nob, pol, por, ron, rus, slo, slv, spa, swe, tur, ukr, vie, zsm

Fonts

Languages

zhs, zht

Fonts

Languages

jpn

Fonts

Languages

kor

Fonts

Languages

tha

Fonts

Approach® S60

App Types

Color Palette

1 Field Layout

2 Fields Layout

3 Fields Layout

Part Number 006-B2656–00

Languages

ara, ces, dan, deu, dut, eng, fin, fre, gre, heb, hrv, hun, ind, ita, nob, pol, por, rus, slo, slv, spa, swe, zsm

Fonts

Part Number 006-B2907–00

Languages

eng, ind, zsm

Fonts

Languages

zhs

Fonts

Languages

zht

Fonts

Languages

jpn

Fonts

Languages

kor

Fonts

Languages

tha

Fonts

Approach® S62

App Types

Color Palette

1 Field Layout

2 Fields Layout

3 Fields A Layout

3 Fields B Layout

4 Fields Layout

Part Number 006-B3393–00

Languages

ara, bul, ces, dan, deu, dut, eng, est, fin, fre, gre, heb, hrv, hun, ita, lav, lit, nob, pol, por, ron, rus, slo, slv, spa, swe, tur, ukr

Fonts

Part Number 006-B3700–00

Languages

eng, ind, zsm

Fonts

Languages

zhs

Fonts

Languages

zht

Fonts

Languages

jpn

Fonts

Languages

kor

Fonts

Languages

tha

Fonts

Languages

vie

Fonts

Approach® S70 42mm

App Types

1 Field Layout

2 Fields Layout

3 Fields A Layout

3 Fields B Layout

3 Fields C Layout

4 Fields A Layout

4 Fields B Layout

4 Fields C Layout

5 Fields Layout

6 Fields A Layout